home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / graphics / font3d10.zip / Font3D.TXT < prev    next >
Text File  |  1994-09-26  |  11KB  |  301 lines
  1.  
  2.                                   Font3D
  3.                     3-D Character Description Generator
  4.                     -----------------------------------
  5.  
  6.                                User's Guide
  7.  
  8.  
  9.                     Copyright (c) 1994, Todd A. Prater.
  10.  
  11. ==============================================================================
  12.  
  13.  
  14.  
  15. A Note from the Author
  16. ----------------------
  17.  
  18.    There are many features I would like to add to the next release of
  19. Font3D.  They include:
  20.  
  21.    o  An MS-DOS Executable.
  22.    o  The ability to use Adobe PostScript Type 1 font descriptions
  23.    o  The ability to create entire strings of text at once
  24.    o  Special Effects such as beveling and rounding of edges
  25.    o  The ability to read TrueType font files with only Macintosh
  26.       character mappings
  27.    o  More output formats
  28.    o  Graphical interfaces for OS/2 and Windows users
  29.  
  30. Some of these are more difficult than others, but all will eventually find
  31. their way into the program.  Since the Adobe Type 1 specification is, at
  32. least for me, fairly expensive, and since I have spent quite alot of time
  33. on this project, I have decided to ask for a small donation from those of
  34. you who find this program useful.  I am not going to make a big issue of
  35. this, but please do take the time to read the file 'Register.TXT'.  There
  36. are several advantages to registering, not the least of which is automatic
  37. upgrades to future versions.  
  38.  
  39.    I had originally intended to only distribute an OS/2 executable file,
  40. along with documentation.  Many people have since convinced me that this
  41. policy would needlessly exclude a large number of POV users.  Although I
  42. have spent many thousands of hours programming in PC-type environments,
  43. my knowledge of UNIX leaves much to be desired.  Hopefully, my code
  44. is reasonably portable, but this is definitely the area in which I would
  45. most like to hear your comments and/or suggestions.
  46.  
  47.    Finally, please take a look at the file 'ReadMe.TXT'.  Any last-minute
  48. changes to the documentation or program will be in there, as well as known
  49. bugs at the time of release.
  50.  
  51.    Thank you for trying Font3D!
  52.  
  53.  
  54.  
  55. Introduction
  56. ------------
  57.  
  58.    Font3D is a utility for the creation of a three-dimensional character
  59. descriptions in a variety of formats including:
  60.  
  61.    o  POV-Ray triangles
  62.    o  POV-Ray smooth_triangles
  63.    o  RAW triangles
  64.  
  65. Any typeface can be used for which you have a TrueType font file
  66. description (*.TTF), and there are a number of other options available for
  67. fine-tuning the program's output.
  68.  
  69.    This document describes how to install and use the Font3D utility, as
  70. well as what to do if you have any questions, comments, or suggestions.
  71.  
  72.  
  73.  
  74. Files in this Distribution
  75. --------------------------
  76.  
  77.    The following files are included in the distribution of Font3D:
  78.  
  79.       ReadMe.TXT ......... Last minute changes (Please Read!)
  80.       Register.TXT ....... Registration information (Please Read!)
  81.       Font3D.TXT ......... Font3D User's Manual
  82.       Font3D.EXE ......... OS/2 Executable
  83.       F3D-SRC.ZIP ........ Font3D Source Code
  84.  
  85.  
  86.  
  87. Installation
  88. ------------
  89.  
  90.    For OS/2 users, simply copy the file Font3D.EXE to a directory
  91. in your path.  Font3D doesn't require any external configuration
  92. or initialization files, so an executable is all you will need to get
  93. started.  Users on other platforms (ie. LINUX, UNIX, etc...) will need
  94. to build your own executable.  Instructions for doing so (if you need
  95. them) are given in the section 'Compiling the Source Code' later in 
  96. this document.  That's all there is to it!
  97.  
  98.  
  99.  
  100. Getting Started
  101. ---------------
  102.  
  103.    Three parameters are required to be present on the command line every
  104. time you run Font3D.  You must specify an input file (the font to use),
  105. an output file (to be used by the raytracer), and the character code of
  106. the glyph to generate.  Here's an example:  let's say we would like to
  107. generate an 'A' in Times New Roman.  The very simplest way to do this
  108. would be
  109.  
  110.    C:\POV\UTILITY>font3d /itimes.ttf /otms065.inc /c65
  111.  
  112. This command generates a POV-formatted include file named 'tms065.inc',
  113. the skeleton of which looks like
  114.  
  115.    #declare ALPHA_65_XMin   = 0.00
  116.    #declare ALPHA_65_YMin   = 0.00
  117.    #declare ALPHA_65_ZMin   = 0.00
  118.    #declare ALPHA_65_XMax   = 0.583
  119.    #declare ALPHA_65_YMax   = 0.656
  120.    #declare ALPHA_65_ZMax   = 0.1
  121.    #declare ALPHA_65_Width  = 0.583
  122.    #declare ALPHA_65_Height = 0.656
  123.    #declare ALPHA_65_Depth  = 0.1
  124.  
  125.    #declare ALPHA_65 =
  126.    union
  127.    {
  128.      // Lots of little triangles go here...
  129.    }
  130.  
  131. Most of the character will usually be inside a unit square, but parts of
  132. some letters (especially ones with descenders like 'q' or 'g', and italics)
  133. may not.  Also, you can usually count on the baseline of the font being at
  134. Y=0.  By default the depth of the generated output is 0.1 units, but this
  135. may be altered with the '/d' command line switch.
  136.  
  137.    Once your output file is generated (ie. 'tms065.inc'), you can include it
  138. in a POV scene description, and then use the #declared object any way you
  139. like.  For example:
  140.  
  141.    ...
  142.    #include "tms065.inc"
  143.    ...
  144.  
  145.    object 
  146.    { 
  147.       ALPHA_65 
  148.       pigment { White } 
  149.       finish { Dull }
  150.       translate <0,0,4>
  151.    }
  152.  
  153.    object
  154.    {
  155.       ALPHA_65
  156.       pigment { Red }
  157.       finish { Shiny }
  158.       translate <-ALPHA_65_Width/2,-ALPHA_65_Height/2,-ALPHA_65_Depth/2>
  159.       scale <10,10,10>
  160.    }
  161.  
  162.    If you're using more than one typeface, you will probably need to
  163. use the '/n' command line switch to give each generated object a unique
  164. name.  Instead of generating an object #declared as 'ALPHA_xxx' the
  165. specified string after the '/n' will be used:
  166.  
  167.    C:\POV\UTILITY>font3d /itimes.ttf /otms065.inc /c65 /nTimes_65
  168.  
  169. generates output like
  170.  
  171.    #declare Times_65_XMin = 0.00
  172.    #declare Times_65_YMin = 0.00
  173.    ...
  174.    #declare Times_65 =
  175.    {
  176.       ...
  177.    }
  178.  
  179.    Probably the best way to learn how to use Font3D is to play around with
  180. it.  As a side note, some options are not compatible with each other.  For
  181. example: if the '/fr' option is used (generating RAW output), both '/n' and
  182. '/t' switches will be ignored, because they apply only to POV formatted 
  183. output.
  184.  
  185.  
  186.  
  187. Command Line Options
  188. --------------------
  189.  
  190.    /cnnn       Character code of the object to create.  Currently, this 
  191.                must be an integer between zero and 255.  Most TrueType 
  192.                fonts use ASCII codes for letters, numbers, and punctuation
  193.                marks, but you may have to experiment to find codes for 
  194.                special-purpose glyphs. (REQUIRED)
  195.  
  196.    /dnn.nn     Depth of the object.  The default value is 0.1 units, which
  197.                creates a character whose front face is at Z=0.1, and whose
  198.                back face is at z=0.
  199.  
  200.    /fr         Generate RAW triangle output.  Options not available with
  201.                this format are '/n' and '/t'.
  202.  
  203.    /fs         Generate a POV formatted output file that uses smooth
  204.                triangles for the sides of a character.  This allows you
  205.                to use a lower curve resolution (for less triangles, and
  206.                faster rendering times), to produce better looking
  207.                objects.
  208.  
  209.    /ifilename  Filename of the TrueType Font to use as a typeface.  It
  210.                must be a 'Windows' TrueType font; 'Macintosh' fonts are
  211.                not yet supported. (REQUIRED)
  212.  
  213.    /nstring    Specifies a string from which all #declared objects in the
  214.                output file will be base.  If this option is not used, the
  215.                default string is 'ALPHA_nnn', where 'nnn' is the character
  216.                code of the glyph being generated. 
  217.  
  218.    /ofilename  Name of the output file to generate. (REQUIRED)
  219.  
  220.    /rnnn       Curve resolution (a positive integer).  The outlines that 
  221.                describe a character are stored in the font file as a series 
  222.                of both lines and curves.  Font3D must approximate the curves
  223.                as a series of short line segments, and this option allows for
  224.                control over how many of these segments are used for each
  225.                curve.  The default value is 5.  Be careful, objects can
  226.                become unwieldy if too large a curve resolution is used.
  227.  
  228.    /tnnn       Angle threshold in degrees (an integer between 0 and 360).
  229.                This value sets a limiting angle below which adjacent facets
  230.                along the edge of a character will be smoothed together.
  231.                Usually, the default value of 20 degrees seems to work well.
  232.  
  233.  
  234.  
  235. Compiling the Source Code
  236. -------------------------
  237.  
  238.    The source code should compile without modification under the following
  239. OS/Compiler combinations:
  240.  
  241.    o  MS-DOS 5.0/Borland C++ 3.1
  242.    o  IBM OS/2 2.1/IBM CSet++ 2.1
  243.    o  Sun OS 4.1/GNU C++ 5.2.4
  244.  
  245. As I have said before, I have very little experience with workstation-type
  246. environments.  Hopefully, I have documented the code well enough for you
  247. to make any changes necessary for compilation on your machine, and I 
  248. encourage you to let me know if any modifications are needed.  The archive 
  249. 'F3D-SRC.ZIP' contains the following files:
  250.  
  251.    Source Files:
  252.  
  253.       build.cc ..........Routines that build the face and edges of an object.
  254.       font3d.cc .........Contains the command line parser, and a routine to
  255.                          create and output the object.
  256.       geometry.cc .......Implements the triangle and polygon classes.
  257.       truetype.cc .......Implements the class 'TTFont'.
  258.  
  259.    Header Files:
  260.  
  261.       Array.H ...........Implements a 'large' array template.  Allows MS-DOS
  262.                          machines to allocate arrays larger than 64K.
  263.       Build.H ...........Header for 'build.cc'.
  264.       Config.H ..........Data types and enumerations.
  265.       Font3D.H ..........Header for 'font3d.cc'.
  266.       Geometry.H ........Header for 'geometry.cc'.  Contains definitions for
  267.                          the 'TRIANGLE' and 'POLYGON' classes.
  268.       List.H ............A simple Linked-List class template.
  269.       TrueType.H ........Header for 'truetype.cc.  Contains definitions for
  270.                          the 'TTFont' class.
  271.       Vector.H ..........Defines a vector class.
  272.  
  273.  
  274.  
  275. Coming Soon...
  276. --------------
  277.  
  278.    At the very top of my list of things to do is making Font3D capable of
  279. reading Macintosh Truetype Fonts.  This is really a very simple matter,
  280. I just haven't had time to do it yet.  Also, those of you that have looked
  281. at the source code may have noticed an attempt at beveling edges.  I have
  282. made alot of progress in this area, but my algorithm doesn't always work,
  283. so I decided to disable it for now.
  284.  
  285.    As far as Postscript Font capability is concerned, I will probably wait
  286. until I see some interest in this program before I buy the specification.
  287. If anyone knows where I can get a cheap copy, let me in on it!
  288.  
  289.  
  290.  
  291. How to Contact Me
  292. -----------------
  293.  
  294.    E-Mail:   squid@ksu.ksu.edu
  295.    USPS:     Todd A. Prater
  296.              1016 Vattier St.  Apt. A
  297.              Manhattan, KS.  66502
  298.    Phone:    (913) 776-3597 (No Collect Calls)
  299.  
  300.  
  301.